- @title = 'Accordions'
:textile
  h3. Accordions
  
  @Ojay.Accordion@ implements the well-known accordion menu widget. It allows for both
  horizontal and vertical collapse directions, and allows the animation to be configured. Like
  all Ojay widgets, it comes with a set of events that you can use to couple an accordion
  instance to other parts of your application.
 
  h3. Required files
  
  * @http://yui.yahooapis.com/2.6.0/build/yahoo-dom-event/yahoo-dom-event.js@
  * @http://yui.yahooapis.com/2.6.0/build/selector/selector-beta.js@
  * @http://yui.yahooapis.com/2.6.0/build/animation/animation.js@
  * @http://yoursite.com/ojay/js-class.js@
  * @http://yoursite.com/ojay/core.js@
  * @http://yoursite.com/ojay/pkg/accordion.js@
  
  To manage history and allow sections to be bookmarked:
  
  * @http://yui.yahooapis.com/2.6.0/build/history/history.js@
  * @http://yoursite.com/ojay/pkg/history.js@
  
  h3. Examples
  
  * "Accordion menu extended with extra effects":/examples/extended_accordion.html
  
  h3. Creating an accordion
  
  Creating an accordion is straightforward. Start with a list of elements, each of which
  should contain an element that you want to collapse. For example:
 
  <pre>
  <div class="section">
      <h3>Section 1</h3>
      <p>Lorem ipsum...</p>
  </div>
  <div class="section">
      <h3>Section 2</h3>
      <p>Dolor sit amet...</p>
  </div>
  <div class="section">
      <h3>Section 3</h3>
      <p>Quaniam omnes...</p>
  </div></pre>
 
  In this example, the paragraphs will collapse and the headings will be the menu tabs.
  The following script sets up the menu:
 
  <pre>
  var acc = new Ojay.Accordion('horizontal',
          '.section', 'p');
  acc.setup();</pre>
 
  This will make a few changes to the markup, which you'll need to be aware of in order
  to apply CSS. After the script runs, the document will look like this:
 
  <pre>
  <div class="section accordion-section">
      <h3>Section 1</h3>
  </div>
  <div class="accordion-collapsible">
      <p>Lorem ipsum...</p>
  </div>
  <div class="section accordion-section">
      <h3>Section 2</h3>
  </div>
  <div class="accordion-collapsible">
      <p>Dolor sit amet...</p>
  </div>
  <div class="section accordion-section">
      <h3>Section 3</h3>
  </div>
  <div class="accordion-collapsible">
      <p>Quaniam omnes...</p>
  </div></pre>
 
  The original sections get an additional class to indicate that they're part of an
  @Accordion@ instance, and the collapsible elements get placed inside a new wrapper
  element, outside their original parent. This seems a little odd but is required to work
  around a layout bug in WebKit.
  
  h3. Custom events and API
  
  The @Ojay.Accordion@ class exposes some events that you can hook into when sections collapse
  and/or expand. These events are called @sectionexpand@ and @sectioncollapse@, and the
  listeners for them are passed the @Accordion@ instance, the index of the relevant section
  (numbered from zero) and an object reperesenting the section, that you can use to
  add extra effects to the collapse/expand transition. For example, to cause the section to
  fade in when it expands, you can do the following:
  
  <pre>
  acc.on('sectionexpand', function(acc, i, section) {
      section.getCollapser().animate({opacity: {from: 0, to: 1}}, 0.3);
  });</pre>
  
  See "the example":/examples/extended_accordion.html to see this code in action. The
  variable @section@ is an instance of @Ojay.Accordion.Section@, which has the following
  methods in its API:
  
  * @section.collapse(animate = true)@ - collapses the section, using animation by default.
    The optional argument, if set to @false@, stops animation.
  * @section.expand(animate = true)@ - expands the section, using animation by default.
    The optional argument, if set to @false@, stops animation.
  * @section.getContainer()@ - returns an @Ojay@ collection wrapping the click target
    element for the section, i.e. the element marked with the class @accordion-section@.
  * @section.getCollapser()@ - returns an @Ojay@ collection wrapping the collapsible part
    of the section, i.e. the element marked with the class @accordion-collapsible@.
  
  The @Ojay.Accordion@ class itself also lets you expand/collapse sections by numeric
  index, numbered from zero. So, these methods are available on the @acc@ object in the
  above examples:
  
  * @acc.expand(n, animate = true)@ - expands section number @n@, using animation unless
    the second parameter is set to @false@.
  * @acc.collapse(n, animate = true)@ - collapses section number @n@, using animation unless
    the second parameter is set to @false@.
  
  h3. History management
  
  @Ojay.Accordion@ is compatible with "@Ojay.History@":/articles/history.html, allowing
  the state of the menu (in terms of which section is open) to be bookmarked and navigated
  using the browser's back/forward buttons. To add history management to an accordion,
  make sure to call @Ojay.History@ before you call @setup()@:
  
  <pre>
  var acc = new Ojay.Accordion('horizontal',
          '.section', 'p');
  
  Ojay.History.manage(acc, 'menu');
  acc.setup();</pre>
  
  Remember to call @Ojay.History.initialize()@ once all your objects are registered.
  See the "history documentation":/articles/history.html for more info.
